home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Xm / XmGetPixmapByDepth.z / XmGetPixmapByDepth
Encoding:
Text File  |  2002-10-03  |  20.1 KB  |  331 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh - A pixmap caching function that
  10.           generates a pixmap, stores it in a pixmap cache, and returns
  11.           the pixmap
  12.  
  13.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.           #include <Xm/Xm.h>
  15.           PPPPiiiixxxxmmmmaaaapppp XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh(
  16.           SSSSccccrrrreeeeeeeennnn ****ssssccccrrrreeeeeeeennnn,
  17.           cccchhhhaaaarrrr ****iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee,
  18.           PPPPiiiixxxxeeeellll ffffoooorrrreeeeggggrrrroooouuuunnnndddd,
  19.           PPPPiiiixxxxeeeellll bbbbaaaacccckkkkggggrrrroooouuuunnnndddd,
  20.           iiiinnnntttt ddddeeeepppptttthhhh);
  21.  
  22.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  23.           This page documents Motif 2.1.
  24.  
  25.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  26.           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh uses the parameter data to perform a
  27.           lookup in the pixmap cache to see if a pixmap has already
  28.           been generated that matches the data. If one is found, a
  29.           reference count is incremented and the pixmap is returned.
  30.           Applications should use XXXXmmmmDDDDeeeessssttttrrrrooooyyyyPPPPiiiixxxxmmmmaaaappppwhen the pixmap is no
  31.           longer needed.
  32.  
  33.           _s_c_r_e_e_n    Specifies the display screen on which the pixmap
  34.                     is to be drawn
  35.  
  36.           _i_m_a_g_e__n_a_m_e
  37.                     Specifies the name of the image to be used to
  38.                     generate the pixmap
  39.  
  40.           _f_o_r_e_g_r_o_u_n_d
  41.                     Combines the image with the _f_o_r_e_g_r_o_u_n_d color to
  42.                     create the pixmap if the image referenced is a
  43.                     bit-per-pixel image
  44.  
  45.           _b_a_c_k_g_r_o_u_n_d
  46.                     Combines the image with the _b_a_c_k_g_r_o_u_n_d color to
  47.                     create the pixmap if the image referenced is a
  48.                     bit-per-pixel image
  49.  
  50.           _d_e_p_t_h     Specifies the depth of the pixmap
  51.  
  52.           If a matching pixmap is not found, _i_m_a_g_e__n_a_m_e is used to
  53.           perform a lookup in the image cache. If an image is found,
  54.           it is used to generate the pixmap, which is then cached and
  55.           returned.
  56.  
  57.           If an image is not found, _i_m_a_g_e__n_a_m_e is used as a filename,
  58.           and a search is made for an XXXX11110000 or XXXX11111111 bitmap file. If it is
  59.           found, the file is read, converted into an image, and cached
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 10/3/02)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           in the image cache. The image is then used to generate a
  75.           pixmap, which is cached and returned.
  76.  
  77.           If _i_m_a_g_e__n_a_m_e has a leading / (slash), it specifies a full
  78.           pathname, and XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh opens the file as
  79.           specified.  Otherwise, _i_m_a_g_e__n_a_m_e specifies a filename.  In
  80.           this case, XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh looks for the file along a
  81.           search path specified by the XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH environment
  82.           variable or by a default search path, which varies depending
  83.           on whether or not the XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR environment variable is
  84.           set.  The default search path contains a lot of directories.
  85.           Therefore, XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh will need a relatively long
  86.           time to search through all these directories for pixmaps and
  87.           bitmaps. Applications that use a lot of pixmaps and bitmaps
  88.           will probably run more quickly if XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH is set to a
  89.           short list of directories.  In addition to X bitmap files
  90.           (XBM), Motif also supports XPM (X Pixmap) file formats. The
  91.           XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH specifies the path for both XBM and XPM files.
  92.           XPM files are described in more detail later in this
  93.           reference page.
  94.  
  95.           The XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH environment variable specifies a search path
  96.           for X bitmap files.  It can contain the substitution field
  97.           %%%%BBBB, where the _i_m_a_g_e__n_a_m_eargument to XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh is
  98.           substituted for %%%%BBBB.  It can also contain the substitution
  99.           fields accepted by XXXXttttRRRReeeessssoooollllvvvveeeePPPPaaaatttthhhhnnnnaaaammmmeeee.  The substitution
  100.           field %%%%TTTT is always mapped to _b_i_t_m_a_p_s, and %%%%SSSS is always
  101.           mapped to NULL.
  102.  
  103.           If XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH is not set, but the environment variable
  104.           XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR is set, the following pathnames are searched:
  105.  
  106.              +o  %%%%BBBB
  107.  
  108.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  109.  
  110.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  111.  
  112.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  113.  
  114.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  115.  
  116.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  117.  
  118.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  119.  
  120.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  121.  
  122.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  123.  
  124.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 10/3/02)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))
  137.  
  138.  
  139.  
  140.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%BBBB
  141.  
  142.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  143.  
  144.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  145.  
  146.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  147.  
  148.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  149.  
  150.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  151.  
  152.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  153.  
  154.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  155.  
  156.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  157.  
  158.              +o  ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  159.  
  160.           If neither XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH nor XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR is set, the following
  161.           pathnames are searched:
  162.  
  163.              +o  %%%%BBBB
  164.  
  165.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  166.  
  167.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  168.  
  169.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  170.  
  171.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  172.  
  173.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  174.  
  175.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  176.  
  177.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  178.  
  179.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  180.  
  181.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%BBBB
  182.  
  183.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  184.  
  185.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  186.  
  187.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  188.  
  189.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  190.  
  191.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 10/3/02)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))
  203.  
  204.  
  205.  
  206.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  207.  
  208.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  209.  
  210.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  211.  
  212.              +o  ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  213.  
  214.           These paths are defaults that vendors may change.  For
  215.           example, a vendor may use different directories for
  216.           ////uuuussssrrrr////lllliiiibbbb////XXXX11111111 and ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111.
  217.  
  218.           The following substitutions are used in these paths:
  219.  
  220.           %%%%BBBB        The image name, from the _i_m_a_g_e__n_a_m_e argument
  221.  
  222.           %%%%NNNN        The class name of the application
  223.  
  224.           %%%%LLLL        The display's language string.  This string is
  225.                     influenced by XXXXttttSSSSeeeettttLLLLaaaannnngggguuuuaaaaggggeeeePPPPrrrroooocccc.  The default
  226.                     string is determined by calling setlocale(_L_C__A_L_L,
  227.                     _N_U_L_L).
  228.  
  229.           %%%%llll____%%%%tttt     The language and territory component of the
  230.                     display's language string
  231.  
  232.           %%%%llll        The language component of the display's language
  233.                     string
  234.  
  235.           The contents of the file must conform to the rules for X11
  236.           bitmap files. In other words, Motif can read any X11
  237.           conformant bitmap file.
  238.  
  239.           The XPM file format is used for storing or getting back
  240.           colored X pixmaps from files. The XPM library is provided as
  241.           unsupported with Motif. To build applications without XPM,
  242.           use the _N_O__X_P_M macro.  The following shows both XBM and XPM
  243.           files, respectively, for a plaid pattern.
  244.  
  245.           /* XBM file */
  246.           #define plaid_width 22
  247.           #define plaid_height 22
  248.           #define plaid_x_hot -1
  249.           #define plaid_y_hot -1
  250.           static char plaid_bits[] = {
  251.              0x75, 0xfd, 0x3f, 0xaa, 0xfa, 0x3e, 0x75, 0xfd, 0x3f, 0xaa, 0xfa, 0x3e,
  252.              0x75, 0xfd, 0x3f, 0xff, 0x57, 0x15, 0x75, 0xfd, 0x3f, 0xaa, 0xfa, 0x3e,
  253.              0x75, 0xfd, 0x3f, 0xaa, 0xfa, 0x3e, 0x75, 0xfd, 0x3f, 0x20, 0xa8, 0x2b,
  254.              0x20, 0x50, 0x15, 0x20, 0xa8, 0x2b, 0x20, 0x50, 0x15, 0x20, 0xa8, 0x2b,
  255.              0xff, 0xff, 0x3f, 0x20, 0xa8, 0x2b, 0x20, 0x50, 0x15, 0x20, 0xa8, 0x2b,
  256.              0x20, 0x50, 0x15, 0x20, 0xa8, 0x2b};
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 10/3/02)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh((((3333XXXX))))
  269.  
  270.  
  271.  
  272.           /* XPM file */
  273.           static char * plaid[] = {
  274.           /* plaid pixmap
  275.            * width height ncolors chars_per_pixel */
  276.           "22 22 4 2 ",
  277.           /* colors */
  278.           "   c red       m white  s light_color ",
  279.           "Y  c green     m black  s lines_in_mix ",
  280.           "+  c yellow    m white  s lines_in_dark ",
  281.           "x              m black  s dark_color ",
  282.           /* pixels */
  283.           "x   x   x x x   x   x x x x x x + x x x x x ",
  284.           "  x   x   x   x   x   x x x x x x x x x x x ",
  285.           "x   x   x x x   x   x x x x x x + x x x x x ",
  286.           "  x   x   x   x   x   x x x x x x x x x x x ",
  287.           "x   x   x x x   x   x x x x x x + x x x x x ",
  288.           "Y Y Y Y Y x Y Y Y Y Y + x + x + x + x + x + ",
  289.           "x   x   x x x   x   x x x x x x + x x x x x ",
  290.           "  x   x   x   x   x   x x x x x x x x x x x ",
  291.           "x   x   x x x   x   x x x x x x + x x x x x ",
  292.           "  x   x   x   x   x   x x x x x x x x x x x ",
  293.           "x   x   x x x   x   x x x x x x + x x x x x ",
  294.           "          x           x   x   x Y x   x   x ",
  295.           "          x             x   x   Y   x   x   ",
  296.           "          x           x   x   x Y x   x   x ",
  297.           "x x x x x x x x x x x x x x x x x x x x x x ",
  298.           "          x           x   x   x Y x   x   x ",
  299.           "          x             x   x   Y   x   x   ",
  300.           "          x           x   x   x Y x   x   x ",
  301.           "          x             x   x   Y   x   x   ",
  302.           "          x           x   x   x Y x   x   x "
  303.           };
  304.  
  305.      RRRREEEETTTTUUUURRRRNNNN
  306.           Returns a pixmap when successful; returns
  307.           XXXXmmmmUUUUNNNNSSSSPPPPEEEECCCCIIIIFFFFIIIIEEEEDDDD____PPPPIIIIXXXXMMMMAAAAPPPPif the image corresponding to _i_m_a_g_e__n_a_m_e
  308.           cannot be found.
  309.  
  310.      RRRREEEELLLLAAAATTTTEEEEDDDD
  311.           XXXXmmmmDDDDeeeessssttttrrrrooooyyyyPPPPiiiixxxxmmmmaaaapppp(3), XXXXmmmmIIIInnnnssssttttaaaallllllllIIIImmmmaaaaggggeeee(3), and
  312.           XXXXmmmmUUUUnnnniiiinnnnssssttttaaaallllllllIIIImmmmaaaaggggeeee(3).
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.      Page 5                                          (printed 10/3/02)
  328.  
  329.  
  330.  
  331.